cmdparse
Section: User Commands (1)
Index
Return to Main Contents
NAME
cmdparse - parse command-line arguments for shell-scripts
SYNOPSIS
- cmdparse
-
[-anywhere]
[-ignore-case]
[-noabort]
[-noguessing]
[-prompt]
[-plus]
[-options-only]
[-keywords-only]
[-quiet]
[-arrays]
[-usage]
[-version]
[-true string]
[-false string]
[-suffix string]
[-shell shellname]
[-file filename]
[-env varname]
[-decls string]
program-name
arguments ...
DESCRIPTION
cmdparse will parse the user's command-line arguments using the
CmdLine(3) library (taking into account any user-specified
preferences) and will print on standard output, a host of variable
settings using the syntax of the specified shell. The user must then
"evaluate" the output of cmdparse in order to set the corresponding
variables for his (or her) shell-script.
If none of -file, -env, or -decls is given then
the argument declarations will be read from standard input (unless
standard input is associated with a terminal, in which case an error
will result).
If more than one of -file, -env, or -decls is given
then argument declarations are read from all the places specified but
in the following order:
-
First, argument declarations are read from the string supplied with the
-decls option.
Second, any argument declarations contained in the environment variable
specified by the -env option are appended to the current set of
argument declarations.
Lastly, any argument declarations contained in the file specified
by the -file option are appended to the current set of
argument declarations.
The order in which the set of argument declarations are processed is important
because any positional parameters that were specified are expected to occur
in the same order as the order in which the corresponding argument declarations
were processed.
Depending upon which shell you are using, you may want to evaluate the output
of cmdparse directly (as in "eval $cmdparse_output") or you may wish to
first redirect output to a file and then evaluate it (as in ". cmdparse_output"). Some shells may not preserve all the special
characters (such as a newline) correctly when the former approach is used.
Other shells may not permit you to change the value of "local" variables
in "sourced" files when the latter approach is used. You will have to
decide which approach to use based upon your needs, and the shell you are
using.
EXAMPLE
#!/bin/sh
#
# Here is a Bourne Shell script named "cmdname".
#
# The short-option syntax is:
# cmdname [-c number] [-x] [-s char]
# input-file [output-file ]
#
# The long-option syntax is:
# cmdname [count number] [xmode] [separator char]
# input-file [output-file ]
#
NAME="`basename $0`"
## Declare the arguments.
ARGS='
ArgInt count "[c|count number]" "number of copies to print."
ArgBool xflag "[x|xmode]" "turn on x-mode."
ArgChar fdsep "[s|separator char]" "field-separator to use."
ArgStr input "input-file" "input file to read."
ArgStr output "[output-file ]" "where to print output."
'
## Parse the arguments
if cmdparse -shell=sh -decls="$ARGS" $NAME "$@" > tmp$$
then
## Success - evaluate the result.
. tmp$$
rm -f tmp$$
else
## Either usage was printed or we found a syntax error.
EXITVAL=$?
rm -f tmp$$
exit $EXITVAL
fi
## Print the arguments
echo "xflag=" $xflag
echo "count=" $count
echo "fdsep=" $fdsep
echo "input=" $input
if [ "$output" ] ; then
echo "output=" $output
fi
OPTIONS
Only a unique prefix of each option-name needs to be given (and the
options are matched case-insensitive).
The possible options are as follows:
- -anywhere
-
Allow options (and keywords) to follow positional parameters.
Unless this option is specified, anything that follows a positional
parameter that resembles an option (begins with a `-') will be
treated as yet another positional parameter.
- -ignore-case
-
Ignore character case on single-character options.
- -noabort
-
Don't exit if improper command-line syntax was used. Just ignore the
errors and continue parsing.
- -noguessing
-
By default, if an unknown single-character option appears on the command-line,
cmdparse will "guess" by seeing if the option corresponds to a keyword.
Similarly, if an unknown keyword (long-option) is encountered, cmdparse
will see if it matches a single-character option. Specifying this option
disables this behavior.
- -prompt
-
Prompt the user interactively for any missing required arguments.
- -plus
-
Allow the prefix ``+'' to be used to indicate a long-option.
(this may also be specified by saying -+).
- -options-only
-
Don't match keywords (long-options). Look only for single-character options.
- -keywords-only
-
Don't match options. Look only for keywords (long-options). Using this
option also allows the single-character option prefix (`-') to be used
for long-options.
- -quiet
-
Don't print command-line syntax error messages.
- -arrays
-
Use alternative syntax for arrays. See the appropriate subsection of
the section SHELLS to see how (and if) this option will affect
the output of cmdparse.
- -usage
-
Print command-line usage and exit. Don't parse anything!
- -version
-
Print version information and exit. Don't parse anything!
- -true string
-
The string to use for boolean arguments that are turned on.
The default string is "TRUE" (unless the perl or tcl shells
are used, in which case the default is "1").
- -false string
-
The string to use for boolean arguments that are turned off.
The default string is "" (unless the perl or tcl shells
are used, in which case the default is "0").
- -suffix string
-
When no value is supplied for an option that takes an optional value,
the variable namesuffix, is set to TRUE (where name
is the name of the corresponding variable and suffix is the string
argument given to this option). If this option is not specified then
the suffix "_FLAG" will be used.
- -shell shellname
-
Set program arguments using the syntax of the given shell
(default=sh).
- -file filename
-
The file from which program argument declarations are read.
If filename is ``-'' then standard input is read.
- -env varname
-
The name of the environment variable containing the program argument
declarations.
- -decls string
-
The string that contains the program argument declarations.
-
Indicates the end of options/keywords.
- program-name
-
The name of the program whose arguments are to be parsed.
If desired, the program-name may be specified as a keyword
(instead of positionally) using the syntax -name=program-name.
- arguments ...
-
The program-arguments to be parsed
EXIT STATUS
cmdparse will exit with one of the following status codes:
- 0
-
Arguments were successfully parsed. No syntax errors were found and the
shell-script variable settings have been printed on standard output.
- 1
-
Either usage or version information was explicitly requested. The desired
information was printed on standard diagnostic output. No arguments were
parsed.
- 2
-
Some type of command-line syntax error occurred. Any syntax error messages
have been printed on standard diagnostic output.
- 3
-
An invalid or unknown shell (command-interpreter) was specified on the
command-line to cmdparse. See the section entitled SHELLS
for a list of the known shells.
- 4
-
A syntax error of some type occurred in one or more command-line argument
declarations. Any syntax error messages
have been printed on standard diagnostic output.
man2html: unable to open or read file
../parsing.man
ARGUMENT DECLARATIONS
The syntax for a single argument for cmdparse looks like the following:
-
<arg-type> <arg-name> <syntax> <description>
Where <arg-type> is one of the following (case-insensitive):
-
- ArgInt
-
An integer value (or list of values).
- ArgFloat
-
A floating-point value (or list of values).
- ArgChar
-
A character value (or list of values).
- ArgStr
-
A string value (or list of values).
- ArgBool
-
A boolean flag that is initially FALSE and is turned on
whenever it is matched.
- ArgClear
-
A boolean flag that is initially TRUE and is turned off
whenever it is matched.
- ArgToggle
-
A boolean flag that is initially FALSE and is toggled
whenever it is matched.
- ArgUsage
-
Print usage and exit.
- ArgDummy
-
A dummy argument.
If desired, the leading "Arg" portion of the type-name may be omitted.
The field <arg-name> is simply the name of the variable in your script
that you wish to contain the resultant value from the command-line.
Any default value must be assigned to the variable before invoking
cmdparse.
The fields <syntax> and <description> MUST be enclosed
in either single or double quotes! If you want the character you are using
to quote the field to also appear within the field, then precede the quote
character (inside the quotes) with a backslash (`\').
The <description> is simply a textual description of the argument.
The <syntax> is a little trickier, there are three basic forms of syntax:
-
- "c|keyword"
-
An option that may be matched by -c or by keyword
and takes no value.
- "c|keyword value"
-
An option that may be matched by -c or by keyword
and requires a value.
- "value"
-
A positional parameter.
Note that the option-character MUST precede the keyword-name and that
there must be NO spaces surrounding the `|' in
``c|keyword'' (unless either the option-character or the keyword-name
is intended to be empty). If you wish a keyword to have no corresponding
short-option (or vice versa) than put a blank in the option-character
(or keyword) portion of the syntax declaration.
Any optional parts of the argument should appear inside square-brackets
(`[' and `]') and a list of values is denoted by an ellipsis (`` ...'').
Most options will be inside of square brackets to reflect the fact that
they are "optional".
Some example <syntax> strings follow:
-
- "c|keyword"
-
A required option.
- "[c|keyword]"
-
An option with no value.
- "[c|keyword value]"
-
An option that takes a value.
- "[c|keyword [value]]"
-
An option that takes an optional value.
- "[c|keyword value ...]"
-
An option that takes one or more values.
- "[c|keyword [value ]]"
-
An option that takes zero or more values.
- "value"
-
A required positional parameter.
- "[value]"
-
An optional positional-parameter.
- "[ |keyword]"
-
An option that may be matched by keyword but has no corresponding
single character option.
- "[c| value]"
-
An option that takes a value but has no corresponding keyword name.
- "[c|keyword] value"
-
A required argument that may be matched either positionally or by keyword.
SYNTAX FLAGS
-
Normally, the value to an option may be supplied either in the same
command-line token (as in "-cvalue"), or in a separate token
(as in "-c value").
If desired, the <syntax> field may optionally be followed by a colon
(`:') and one of "SEPARATE" or "STICKY".
The former specifies that the argument value may only occur in a separate
command-line token, the latter specifies that the argument value may only
occur in the same command-line token.
SHELLS
At present, cmdparse knows about the following shells:
-
- sh
-
The Bourne Shell. This shell is the standard Unix shell
(designed and written by Stephen R. Bourne).
- csh
-
The C Shell. Bill Joy's answer to sh using C-like syntax.
- ksh
-
The Korn shell. David G. Korn's shell combining all the "best" features
of sh and csh in a "clean" fashion.
- bash
-
The Bourne Again Shell. The Free Software Foundation's answer to ksh.
- zsh
-
The Z Shell. Paul Falstad's creation combining all the "best" features
of ksh and csh plus some stuff of his own.
- rc
-
The Plan 9 Unix shell designed by Tom Duff. A public domain implementation
(with some enhancements) has been released by Byron Rakitzis.
- perl
-
Larry Wall's practical extraction and report-generation language. Perl is
not a "shell" in the same sense as the others but it is a (powerful) language
in which Unix scripts may be written.
- tcl
-
John K. Ousterhout's Tool Command Language. Karl Lehenbauer and friends have
developed a tcl shell based on Ousterhout's command language.
In addition, ash is considered by cmdparse to be equivalent to
sh; and tcsh and itcsh are considered to be equivalent to
csh.
For each supported shell, cmdparse will output a combination of
shell-variable and/or shell-array settings that correspond to the
arguments that were supplied on the command-line. In addition, if
an argument that takes an optional value was given on the command-line
but NO value was supplied, then the shell-variable named
name_FLAG is assigned the value TRUE (where name
was the name specified in the <arg-name> field of the corresponding
argument declaration). If desired, a suffix other than _FLAG may be
used by specifying the -suffix option.
Any desired initial values for variables from the argument declaration
string should be assigned BEFORE invoking cmdparse.
cmdparse will NOT output variable settings for any arguments
that were NOT supplied on the command-line. The only exception to
this is when a positional argument that corresponds to the positional
parameters of the shell-script is NOT supplied on the command-line;
In this particular case, the positional parameters of the shell-script are
unset (set to an empty list).
The exact syntax used to set variables and arrays for the corresponding
shells is the subject of the next several subsections.
BOURNE SHELL
-
For the Bourne shell, shell variables are assigned using the following syntax:
-
name='value';
Shell arrays are assigned using the following syntax:
name='value1 value2 ';
If the -arrays option was specified then the following syntax is
used to set arrays:
name_count=3;
name1='value1';
name2='value2';
name3='value3';
If the <arg-name> field of an argument is one of "-", "",
"*", or "@" then the argument corresponds to the positional parameters
of the shell-script and the following syntax is used to set its value(s):
set 'value1' 'value2' ;
KORN SHELL
-
For the Korn shell, shell variables are assigned using the following syntax:
-
name='value';
Shell arrays are assigned using the following syntax:
set -A name 'value1' 'value2' ;
If the -arrays option was specified then the following syntax is
used to set arrays:
set +A name 'value1' 'value2' ;
If the <arg-name> field of an argument is one of "-", "",
"*", or "@" then the argument corresponds to the positional parameters
of the shell-script and the following syntax is used to set its value(s):
set 'value1' 'value2' ;
C SHELL
-
For the C shell, shell variables are assigned using the following syntax:
-
set name='value';
Shell arrays are assigned using the following syntax:
set name=('value1' 'value2' ) ;
If the <arg-name> field of an argument is "argv"
then the argument corresponds to the positional parameters
of the script and may be unset.
BOURNE AGAIN SHELL
-
At present, the Bourne Again shell is treated exactly the same as the
Bourne Shell.
Z SHELL
-
For the Z shell, shell variables are assigned using the following syntax:
-
name='value';
Shell arrays are assigned using the following syntax:
name=('value1' 'value2' ) ;
If the <arg-name> field of an argument is one of "-", "",
"*", "@", or "argv" then the argument corresponds to the positional
parameters of the shell-script and the following syntax is used to set its
value(s):
argv=('value1' 'value2' ) ;
PLAN 9 SHELL
-
For rc (the Plan 9 Shell), shell variables are assigned using the
following syntax:
-
name='value';
Shell arrays are assigned using the following syntax:
name=('value1' 'value2' ) ;
If the <arg-name> field of an argument is "*"
then the argument corresponds to the positional parameters
of the script and may be unset.
PERL
-
For Perl, variables are assigned using the following syntax:
-
$name = 'value';
arrays are assigned using the following syntax:
@name = ('value1', 'value2', ) ;
If the <arg-name> field of an argument is "ARGV"
then the argument corresponds to the positional parameters
of the script and may be unset.
A perl interface to cmdparse should have been installed in your
standard perl library when cmdparse was installed. It may be used
by saying:
require "cmdparse.pl" ;
somewhere in your perl-script. This will give you access to a perl function
named "cmdparse" which may be used as follows:
eval &cmdparse("-decls=$ARGDECLS", $0, @ARGV);
Where $ARGDECLS is a variable containing a string of command-line
argument declarations for cmdparse(1). The arguments to the perl function
should be a vector of arguments to pass to cmdparse(1) on the command-line.
The file cmdparse.pl in your perl library directory contains
the implementation and documentation for the perl interface to cmdparse.
If a syntax error occurred on the command-line and -noabort was
not specified then the cmdparse function will terminate the execution of the
perl script and will NOT return to the caller.
TCL
-
For Tcl, variables are assigned using the following syntax:
-
set name "value";
arrays are assigned using the following syntax:
set name [ list "value1" "value2" ];
If the <arg-name> field of an argument is "argv" or
"args" then the argument corresponds to the positional
parameters of the script and may be unset.
A tcl interface to cmdparse should have been installed in your
standard tcl library when cmdparse was installed. It may be used
by saying:
load "cmdparse.tcl" ;
somewhere in your tcl script. This will give you access to a tcl
procedure named "cmdparse" which may be used as follows:
eval [ cmdparse -decls=$argDecls $scriptName $argv ];
Where $argDecls is a variable containing a string of command-line
argument declarations for cmdparse(1).
The arguments to the tcl cmdparse procedure are exactly the same as for
cmdparse(1).
The file cmdparse.tcl in your tcl library directory contains
the implementation and documentation for the tcl interface to cmdparse.
If a syntax error occurred on the command-line and -noabort
was not specified then the cmdparse procedure will terminate the execution of the
tcl script and will NOT return to the caller.
- Note:
-
The tcl cmdparse procedure will only work with tcl scripts that use
a version of the tcl shell that contains the execl command!
man2html: unable to open or read file
../environ.man
FILES
- /cmdparse
-
The executable file for cmdparse(1).
- /cmdparse.pl
-
The perl interface (including documentation) to cmdparse(1).
- /cmdparse.tcl
-
The tcl interface (including documentation) to cmdparse(1).
SEE ALSO
CmdLine(3), cmdargs(3)
man2html: unable to open or read file
../caveats.man
man2html: unable to open or read file
../bugs.man
AUTHOR
Brad Appleton, Harris Computer Systems, <brad@ssd.csd.harris.com>.
Index
- NAME
-
- SYNOPSIS
-
- DESCRIPTION
-
- EXAMPLE
-
- OPTIONS
-
- EXIT STATUS
-
- ARGUMENT DECLARATIONS
-
- SYNTAX FLAGS
-
- SHELLS
-
- BOURNE SHELL
-
- KORN SHELL
-
- C SHELL
-
- BOURNE AGAIN SHELL
-
- Z SHELL
-
- PLAN 9 SHELL
-
- PERL
-
- TCL
-
- FILES
-
- SEE ALSO
-
- AUTHOR
-
This document was created by
man2html,
using the manual pages.
Time: 00:37:13 GMT, March 30, 2022